Tutorial by Yurlungur · Pull Request #1439 · parthenon-hpc-lab/parthenon

Yurlungur · 2026-08-24T00:42:18Z

PR Summary

In preparation for the Parthenon workshops coming up I finally sat down and wrote a tutorial for how to use parthenon. In the end I did not use gen AI as I wanted to convey very specifically the story I wanted to convey. I also made some minor tweaks to Parthenon guts and scripts to make sure the tutorial worked as intended.

I can't include the project I wrote that the tutorial walks through, as it would be a bit recursive. But if someone else wanted to create it in the parthenon namespace and follow the tutorial so we had a complete version, that wouldn't be unwelcome. That would be a good test my instructions work for someone else.

PR Checklist

Yurlungur · 2026-08-24T00:42:36Z

@par-hermes format

… into jmm/turorial

Yurlungur · 2026-08-24T00:51:15Z

@@ -1,4 +1,4 @@
-.. par_for:
+.. _par_for:


This was a typo.

Yurlungur · 2026-08-24T00:51:42Z

-        plt.colorbar(
-            pm, label=colorbar, fontsize=fontsize, fraction=0.02, pad=0.04, ax=p
-        )
+        plt.colorbar(pm, label=colorbar, fraction=0.02, pad=0.04, ax=p)


matplotlib api changed. fontsize can't go here anymore.

Yurlungur · 2026-08-24T01:00:41Z

Tutorial live here: https://parthenon-hpc-lab.github.io/parthenon/jmm/turorial/src/tutorial.html

… into jmm/turorial

Yurlungur · 2026-08-31T19:36:06Z

@pgrete @c-prather please re-review. It should be updated with your suggestions and the issues we found in the live run.

c-prather

Left the changes I had to (one I wanted to) make when updating the compile-able example, and some wording things when going through the text again.

Otherwise LGTM, really excellent stuff and I'm glad we finally have this. Bravo.

lroberts36

This is great!

Co-authored-by: Cora Prather <cprather@radimant.org>

… into jmm/turorial

Yurlungur · 2026-09-10T19:59:44Z

@pgrete is something wrong with the CI machine? Jobs are failing when trying to fetch openpmd from github.

pgrete · 2026-09-10T20:11:38Z

@pgrete is something wrong with the CI machine? Jobs are failing when trying to fetch openpmd from github.

CI machine was restarted and I had to manually fire up the runners again.
They should be available again as of three ours ago.

pgrete

Thanks! Great writeup! This was truly overdue and my impression is that it was well received during the user meeting.

pgrete · 2026-09-10T20:14:59Z

+   mkdir src
+   touch CMakeLists.txt
+   git submodule add git@github.com:parthenon-hpc-lab/parthenon.git external/parthenon
+   git add external parthenon


Suggested change

git add external parthenon

git add external/parthenon

pgrete · 2026-09-10T20:15:54Z

+   Parthenon also has a Spack package (``spackage``). You can see
+   details in our :ref:`build doc <building>`.


ugh, this reminds me that I should update the spack package..
probably even more relevant now given that RIOT is available

pgrete · 2026-09-10T20:17:49Z

+   project(ellipse LANGUAGES C CXX)
+   # We require C++20
+   set(CMAKE_CXX_STANDARD 20)
+   # A useful command for debugging


Suggested change

# A useful command for debugging

# A useful command for debugging as it creates a `compile_commands.json` in your build

# directory containing the exact commands to build the code with a given config.

# Moreover, that file can also be parsed by IDEs for cross referencing.

pgrete · 2026-09-10T20:25:38Z

+Anatomy of a Task
+^^^^^^^^^^^^^^^^^^^


Suggested change

Anatomy of a Task

^^^^^^^^^^^^^^^^^^^

Anatomy of a Task

^^^^^^^^^^^^^^^^^

pgrete · 2026-09-10T20:32:17Z

+     const Real r = std::sqrt(x * x + y * y);
+     const Real th = std::atan2(y, x);


Suggested change

const Real r = std::sqrt(x * x + y * y);

const Real th = std::atan2(y, x);

const Real r = Kokkos::sqrt(x * x + y * y);

const Real th = Kokkos::atan2(y, x);

pgrete · 2026-09-10T20:43:13Z

+             const Real dx = std::min(std::abs(x - xmin), std::abs(xmax - x));
+             const Real dy = std::min(std::abs(y - ymin), std::abs(ymax - y));


Suggested change

const Real dx = std::min(std::abs(x - xmin), std::abs(xmax - x));

const Real dy = std::min(std::abs(y - ymin), std::abs(ymax - y));

const Real dx = Kokkos::min(std::abs(x - xmin), Kokkos::abs(xmax - x));

const Real dy = Kokkos::min(std::abs(y - ymin), Kokkos::abs(ymax - y));

pgrete · 2026-09-10T20:43:32Z

+             // speed times dt, which is r * omega * dt, which must be
+             // less than delta:
+             // dt <= delta / (r * omega)
+             ldt = std::min(ldt, delta / (std::abs(r * omega) + EPS));


Suggested change

ldt = std::min(ldt, delta / (std::abs(r * omega) + EPS));

ldt = Kokkos::min(ldt, delta / (Kokkos::abs(r * omega) + EPS));

pgrete · 2026-09-10T20:46:03Z

+This is very much a toy heuristic for a toy problem. We simply check
+how far away a particle is from the boundaries of its meshblock
+(including ghost cells) and don't let the particle move fast enough to
+leave its current block.


Suggested change

leave its current block.

leave its current block.

Note the use of Kokkos math functions. While not strictly necessary

(`std::` math work just fine on most architectures) using the Kokkos

version ensures portability for future architectures.

pgrete · 2026-09-10T20:50:34Z

+     const IndexRange ib = cellbounds.GetBoundsI(IndexDomain::interior);
+     const IndexRange jb = cellbounds.GetBoundsJ(IndexDomain::interior);
+     const IndexRange kb = cellbounds.GetBoundsK(IndexDomain::interior);


Rotate went over entire, which I assumed to be done because there's no ghost comm.
Is is then fine/consistent to just seed interior?
Probably yes, because on init we communicate Independent no matter what, don't we?

We do. But I think you're right it's a little confusing. I'll change it to entire.

pgrete · 2026-09-10T21:00:09Z

+After the particle positions have been updated, they must be
+communicated across the mesh, which is the role of the next set of tasks:


Suggested change

After the particle positions have been updated, they must be

communicated across the mesh, which is the role of the next set of tasks:

After the particle positions have been updated, the particles now residing in ghost zones must be

communicated to their respective neighboring blocks, which is the role of the next set of tasks:

Yurlungur · 2026-09-11T15:04:40Z

Thanks for the re-review @pgrete . I messed up and merged this before before I addressed your comments. Now in #1452

jonahm-LANL added 6 commits August 22, 2026 15:29

start tutorial

6c3b438

progress

fb9a131

fix

dab546e

finish tutorial

331e7c5

movie2d needed massaging for ffmpeg and colorbars

b5d9c77

make a public function for accessing coords from swarm device

fb0d9ee

Yurlungur requested review from acreyes, c-prather, jdolence, lroberts36, pdmullen and pgrete August 24, 2026 00:42

Yurlungur self-assigned this Aug 24, 2026

Yurlungur added the documentation Improvements or additions to documentation label Aug 24, 2026

par-hermes and others added 4 commits August 24, 2026 00:43

cpp-py-formatter

ac17c28

parthenon tutorial

7ba46ca

Merge branch 'jmm/turorial' of github.com:parthenon-hpc-lab/parthenon…

0c24beb

… into jmm/turorial

Merge branch 'develop' into jmm/turorial

2099050

Yurlungur commented Aug 24, 2026

View reviewed changes

Yurlungur mentioned this pull request Aug 24, 2026

[WIP] two more pedagogical examples #1166

Closed

12 tasks

jonahm-LANL and others added 3 commits August 24, 2026 09:24

tutorial exercises left to the reader

56d771c

spelling etc

af3139c

Merge branch 'develop' into jmm/turorial

0e2c09b

Yurlungur enabled auto-merge August 24, 2026 16:29

jonahm-LANL added 2 commits August 24, 2026 14:03

cora fixes

5c62575

Merge branch 'jmm/turorial' of github.com:parthenon-hpc-lab/parthenon…

ac86153

… into jmm/turorial

pgrete reviewed Aug 24, 2026

View reviewed changes

Comment thread doc/sphinx/src/tutorial.rst Outdated

pgrete reviewed Aug 24, 2026

View reviewed changes

Comment thread doc/sphinx/src/tutorial.rst Outdated

Yurlungur mentioned this pull request Aug 24, 2026

clear particles in pgen #1441

Merged

13 tasks

jonahm-LANL and others added 5 commits August 24, 2026 19:43

fix doc typos in loop abstraction docs...

6f94f0f

update tutorial based on discussions today

2c1b86b

link to complete code

53a52b8

Merge branch 'develop' into jmm/turorial

e3fd0ae

Merge branch 'develop' into jmm/turorial

0c4ff4d

c-prather approved these changes Sep 2, 2026

View reviewed changes

lroberts36 approved these changes Sep 2, 2026

View reviewed changes

Comment thread doc/sphinx/src/tutorial.rst

Yurlungur and others added 9 commits September 2, 2026 16:13

Update doc/sphinx/src/tutorial.rst

755cdaa

Co-authored-by: Cora Prather <cprather@radimant.org>

Update doc/sphinx/src/tutorial.rst

6f7b7bd

Co-authored-by: Cora Prather <cprather@radimant.org>

Update doc/sphinx/src/tutorial.rst

0aa7180

Co-authored-by: Cora Prather <cprather@radimant.org>

Update doc/sphinx/src/tutorial.rst

96c075b

Co-authored-by: Cora Prather <cprather@radimant.org>

Update doc/sphinx/src/tutorial.rst

50e1754

Co-authored-by: Cora Prather <cprather@radimant.org>

cprather and lroberts comments

5865f36

Merge branch 'develop' into jmm/turorial

130261a

more cprather comments

96b2548

Merge branch 'jmm/turorial' of github.com:parthenon-hpc-lab/parthenon…

b06b268

… into jmm/turorial

Yurlungur disabled auto-merge September 2, 2026 20:21

Yurlungur enabled auto-merge September 2, 2026 20:21

pgrete approved these changes Sep 10, 2026

View reviewed changes

Yurlungur merged commit 4a46a9e into develop Sep 11, 2026
42 of 46 checks passed

Yurlungur deleted the jmm/turorial branch September 11, 2026 05:04

Yurlungur mentioned this pull request Sep 11, 2026

update tutorial via pgrete suggestions #1452

Merged

13 tasks

		Parthenon also has a Spack package (``spackage``). You can see
		details in our :ref:`build doc <building>`.

-   # A useful command for debugging
+   # A useful command for debugging as it creates a `compile_commands.json` in your build
+   # directory containing the exact commands to build the code with a given config.
+   # Moreover, that file can also be parsed by IDEs for cross referencing.

		const Real r = std::sqrt(x * x + y * y);
		const Real th = std::atan2(y, x);

		const Real dx = std::min(std::abs(x - xmin), std::abs(xmax - x));
		const Real dy = std::min(std::abs(y - ymin), std::abs(ymax - y));

	ldt = std::min(ldt, delta / (std::abs(r * omega) + EPS));
	ldt = Kokkos::min(ldt, delta / (Kokkos::abs(r * omega) + EPS));

-leave its current block.
+leave its current block.
+Note the use of Kokkos math functions. While not strictly necessary
+(`std::` math work just fine on most architectures) using the Kokkos
+version ensures portability for future architectures.

		After the particle positions have been updated, they must be
		communicated across the mesh, which is the role of the next set of tasks:

Uh oh!

Conversation

Yurlungur commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

Yurlungur commented Aug 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Yurlungur commented Aug 24, 2026

Uh oh!

Uh oh!

Uh oh!

Yurlungur commented Aug 31, 2026

Uh oh!

c-prather left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lroberts36 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Yurlungur commented Sep 10, 2026

Uh oh!

pgrete commented Sep 10, 2026

Uh oh!

pgrete left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Yurlungur commented Sep 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Yurlungur commented Aug 24, 2026 •

edited

Loading